STACKS-905

Introduces @stackoverflow/stacks-email, a new (experimental) MJML powered email package for building, previewing, documenting, and compiling Stack Overflow email templates.

• A reusable email component library
• A template gallery for complete email examples
• A shared MJML compile pipeline
• Target-specific token replacement for preview, .NET/Razor, and Braze
• A flexible Node/TypeScript package API
• A narrower SvelteKit HTTP compile endpoint for service integration
• Static compiled artifacts for use in stacks-docs

Background

Historically, Stack Overflow's email design system lived across several separate implementations, including the monolith and external marketing tools. Since 2020, the system has had limited modernization or maintenance.

This work is part of the 2026 rebrand rollout. The goal is to create a shared source of truth for email design patterns, implementation, previewing, and downstream consumption.

We selected MJML because it is widely adopted, MIT licensed, and abstracts much of the client-specific complexity of writing production email HTML.

Overview

Components

~/packages/stacks-email/components

Adds reusable email building blocks such as Button, Header, Footer, Card etc. Each defines their variants, options, tokens, and MJML render output in one place.

Templates

~/packages/stacks-email/templates

Adds example and reusable template definitions including Transactional, Newsletter, Promotional. These compose components into full MJML documents and can expose variants and props.

Compile APIs

The package can be consumed in several ways:

• As a local/gallery app for previewing emails (this branch is currently live on email.stackoverflow.com)
• As a Node/TypeScript library via @stackoverflow/stacks-email
• As a deployed SvelteKit endpoint via POST /api/compile
• As static compiled artifacts for docs previews
• As raw MJML or compiled HTML output

The package API and HTTP API intentionally serve different use cases.

The package API is the full in-process integration surface for trusted TypeScript consumers. It supports catalog discovery, component compilation, template compilation, renderable dispatch, and lower-level MJML compilation primitives.

The HTTP endpoint is a narrower service integration surface. It currently focuses on composing transactional emails from a validated JSON block list, then returning compiled MJML and HTML. This keeps the cross-service contract small while still enabling non-TypeScript consumers to generate branded email output without embedding the package.

Documentation

Adds a new Email section to stacks-docs, including:

• Email overview
• Template documentation
• Component documentation
• Embedded email previews
• MJML/HTML output tabs
• Usage examples
• Generated options tables

Usage

As a package

import {
    getEmailCatalog,
    compileEmailTemplate,
    compileEmailComponent,
    compileEmailRenderable,
} from "@stackoverflow/stacks-email";

const email = compileEmailTemplate({
    slug: "transactional",
    target: "braze",
    props: {
        headlineText: "Reset your password",
        ctaText: "Reset password",
    },
});

console.log(email.html);

As an endpoint

curl -X POST https://email.stackoverflow.design/api/compile \
  -H "Content-Type: application/json" \
  --data '{
    "template": "transactional",
    "target": "preview",
    "previewText": "Reset your password",
    "blocks": [
      {
        "type": "headline",
        "props": {
          "textContent": "Reset your password"
        }
      },
      {
        "type": "text",
        "props": {
          "textContent": "Click below to continue."
        }
      },
      {
        "type": "button",
        "props": {
          "href": "[[BUTTON_URL]]",
          "text": "Reset password"
        }
      }
    ]
  }'

As static docs artifacts

@stackoverflow/stacks-email/sveltekit exports route handlers used by stacks-docs to serve precompiled email HTML, MJML, and manifest data.

Compile targets

Every compile supports a target:

• preview: replaces tokens with sample values
• dotnet: replaces tokens with Razor model bindings
• braze: replaces tokens with Braze/Liquid-style values

This allows the same email source to produce output for different downstream systems.

Notes for reviewers

Suggested review path:

1. Start with packages/stacks-email/README.md
2. Review the component structure in packages/stacks-email/components
3. Review template composition in packages/stacks-email/templates
4. Review the compile pipeline in packages/stacks-email/src/lib/pipeline
5. Review public API exports in packages/stacks-email/src/lib/api
6. Review the HTTP endpoint in packages/stacks-email/src/routes/api/compile/+server.ts
7. Review docs integration in packages/stacks-docs/src/components/StacksEmailEmbed.svelte
8. Review static artifact handlers under packages/stacks-docs/src/routes/email/compiled

Current limitations / Follow-ups

• This is mostly experimental but wanted to at least get the design elements and static markup available for consumption.
• Open to ideas for a testing strategy for a follow-up PR.
• The endpoint is intentionally narrower than the package API.
• The package compiles email markup; it does not send emails.
• Real inbox/client testing is still required before using output in production sends (Litmus?).
• Additional templates, variants, and target mappings can be added as rollout needs become clearer.
• Production hosting and ownership model should be finalized separately from this package implementation (hi platform team!)
• Add Figma Code Connect
• Sync with tools e.g., Braze API